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IGUANA is a generic interactive visualisation framework based on a CH — h component model. It provides 
powerful user interface and visualisation primitives in a way that is not tied to any particular physics experiment 
or detector design. The article describes interactive visualisation tools built using IGUANA for the CMS and 
DO experiments, as well as generic GEANT4 and GEANT3 applications. It covers features of the graphical user 
interfaces, 3D and 2D graphics, high-quality vector graphics output for print media, various textual, tabular 
and hierarchical data views, and integration with the application through control panels, a command line and 
different multi-threading models. 



1. INTRODUCTION 

IGUANA - Interactive Graphics for User ANAlysis - 
is a modular CH — h toolkit for interactive visualisation. 
The project mainly focuses on interactive detector and 
event visualisation with emphasis on: 

• High performance 2D and 3D graphics; 

• Graphical user interfaces; 

• User access to the experiment services: data 
access framework, application execution frame- 
work, etc. 

The goal of the project is to provide easy-to-use co- 
herent interactive graphical application interface for 
the physicist, where the main application - IGUANA 
studio - interfaces to other tools and components. In- 
teractive histogram, ntuple analysis is not considered 
a primary goal. It is assumed that this functionality 
will be provided by other tools and projects such as 
JAS II, Hippodraw [lcj, ROOT 0, or OpenScien- 
tist [lj], which may (or may not) ultimately be inte- 
grated with IGUANA. 

IGUANA development is mainly driven by the 
needs of the CMS and DO experiments, but most of 
IGUANA is independent of CMS or DO and can be 
freely used by others. In CMS, IGUANA releases are 
available directly via SCRAM [Tj which keeps a list of 
the IGUANA project releases. Instructions versioned 
by release on how to download and install IGUANA 
are available for any selected version. 

IGUANA is currently supported on Linux, Solaris 
and Windows. Porting to other unix varieties is rea- 
sonably straightforward. 



2. ARCHITECTURE AND FRAMEWORK 

IGUANA architecture is designed to provide a 
generic tool that can integrate with a specific exper- 
iment or even a single task within it without having 
to specify a fixed list of abstract interfaces or hav- 
ing to standardise on a common object description. 



IGUANA has a small kernel, everything else is imple- 
mented in demand-loaded extensions which negotiate 
the specific services they need. This allows new ser- 
vices to be added quickly, to be propagated into exist- 
ing code gradually, and existing services to be altered 
to do new things easily. 

The full documentation is available on the project 
website 1 automatically generated for every release 
from the sources kept in CVS. 



2.1. Core Overview 

The main units relating to the IGUANA architec- 
ture are: 

• A thin portability and utilities layer; 

• A small kernel that manages a number of plug- 
ins: 

— application personalities; 

— session with extensions forming the shared 
application state; 

— user interface components: sites, browsers; 

— representation methods to map between 
the experiment objects and the various 
browsers; 

• External software imported into IGUANA for 
convenience of building and distribution, and ex- 
ternal software which remains outside IGUANA. 

The portability layer, is mostly implemented by the 
classlib package which in future will be distributed by 
the LHC Computing Grid (LCG) SEAL project 0. 

The kernel is implemented by IgPluginManager, a 
generic plug-in manager package, which is extended by 
the architecture kernel package IgObjectBrowser that 



1 http:/ /iguana. cern.ch 



MOLT008 



2 



CHEP03, La Jolla, California, March 24-28, 2003 



X-« ORCA Visualisation j ■ n * 



File 3D View Debug. 




Run #1, Evert #201 



Figure 1: ORCA visualisation based on IGUANA: IgSplitter sites (horisontal and vertical) host the 3D browser, the 
Twig browser, and the Text browser. Communication is established among all the browsers: correlated picking from 
the 3D browser window broadcasts selection. The Twig browser responds by highlighting corresponding Twig leaf and 
the text rep in the form of an html text is displayed in the Text browser. 



provides the core functionality: session objects, exten- 
sions, user interface components, representations, etc. 
and base interfaces for the various plug- in types. 

The plug-ins are in the Ig_Modules subsystem which 
includes the event display core, application manage- 
ment services, and thin adaptors to export external 
software in forms understood by the architecture. For 
more details see ||. 

2.2. Application Personalities 

When an IGUANA program runs, it first creates a 
session object into which it then attaches an applica- 
tion personality: the main program that determines 
all subsequent behaviour (IgSession, IgDriver). Typi- 
cally the personality immediately extends the session 
object with services pertinent to the purpose of the 
application (IgExtension). For example, a graphical 
personality would create a main window and add ser- 
vices that give access to the menus and maintain GUI 
event loops. The personality then loads a number 
of extensions into the session; a graphical personal- 
ity would tell the system to load all "GUI extensions" 
(IgExtension) . 

The personality and the extensions form the ap- 
plication. The personality exposes features by in- 
stalling service interfaces into the session, based on 
which other extensions can provide further services 
and make features available to the user. 



2.3. Browsers and Sites 

An interactive application personality creates its 
user interface based on one of the user interface com- 
ponents: browsers and sites (IgBrowser, IgSite). A 
browser is a way to look at and interact with applica- 
tion objects (see Figure 0). It may also control other 
things, such as a cut in a histogram display. A browser 
does not however have to be graphical: it might just 
sit on the background and respond to other browsers' 
queries such as "What actions can be invoked on this 
object?" Sites host browsers, by providing for exam- 
ple a window for a 3D browser view. More generally 
sites expose objects such as GUI widgets as hosts for 
other sites and browsers. Sites need not to be graph- 
ical either: a pipe site might host a browser commu- 
nicating to a subprocess. 

2.4. Object Representations 

Application objects can be represented in many dif- 
ferent browsers. A browser typically has a model 
made of a number of object reps (IgModel, IgRep). 
The use of model-specific reps, such as 3D shape ob- 
jects, is encouraged rather then the application ob- 
jects themselves. This permits an object's representa- 
tion to be separated from the object itself. It is possi- 
ble to correlate the object's reps in different browsers 
and to create a rep in a right context in each browser. 
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This implementation requires "representable" ap- 
plication objects to inherit from a common base type 
(IgRepresentable) or make it an alias for another class. 
The only requirement is that the type must be poly- 
morphic; IgRepresentable simply defines a virtual de- 
structor and no other methods. 

In CMS there is however no base type shared by all 
objects; for visualisation the proxies are used that in- 
herit IgRepresentable and point to other CMS objects. 
The primary reason for this choice is the framework's 
support for "virtual objects" that can be materialized 
upon request. 

The object - rep mappings are extensions loaded 
dynamically on demand. IGUANA discovers and 
chooses the right mapping automatically; the exten- 
sion code simply does whatever is appropriate for that 
combination. It is not necessary to have a global list 
of all the pairings: code for new reps and views can 
be dropped in without any changes to existing code. 

2.5. Communication 

Communication takes place through three channels: 
session extensions, message services, and the object 
mapping methods. The first has already been covered. 
The message services allow browsers to share messages 
such as "I selected this": all observers of a service 
can maintain together a coherent state and to answer 
queries from each other while still knowing next to 
nothing about the message sender (see Figure P). 

The final channel is the object-rep-model opera- 
tions, one of which was already mentioned: the cre- 
ation of a rep. Another operation commits a changed 
rep back to the object, yet another lazily expands an 
object rep (for example to read data only when it is 
requested). The operations can be extended, both 
to handle new argument combinations and with new 
methods with arbitrary parameter types (IgBrowser- 
Methods). 



3. VISUALISATION FRAMEWORK FOR 
GEANT4 

IGUANA provides an interactive visualisation sub- 
framework for GEANT4 5]. The framework im- 
plements DCUT, DTREE-likc functionality (as in 
Geant3). It allows to explore and visualise the vol- 
ume tree, with all the usual IGUANA 3D features: 
view, correlated picking, slices per object, etc. with 
the Geant4 command line still accessible. Navigation 
in the volume tree can be done either by logical or 
physical volumes, or subsets. There are quick oper- 
ations for common tasks. Volume property window 
shows additional information about selected object or 
volume. Volume tree selectors provide various types 
of selection: 



• by material: "show all silicon"; 

• by sensitive: "show only sensitive detectors"; 

• for a sub-tree, predefined viewpoints/settings; 

• forward + reverse: "show where this is used". 

The framework is used in the CMS OSCAR simu- 
lation project where an IGUANA wizard is used to 
guide through GEANT4/OSCAR settings. The ap- 
plication is integrated with Martin Liendl's overlap 
detection: overlaps are found and the result details 
are shown in a list. 

Two generic examples showing how to use an arbi- 
trary GEANT4 geometry with the framework are dis- 
tributed with IGUANA experiment-independent core: 
the GEANT4 example number two and the ATLAS 
calorimeter example. 



4. APPLICATIONS 

There are several applications based on IGUANA 
plug-in architecture. Among those are OSCAR and 
ORCA visualisation which are well known in CMS 
and actively used for visualising simulated and recon- 
structed CMS data. DOScan (see Figure 0) currently 
uses IGUANA as a toolkit. It is used at DO for event 
and detector visualisation. 



4.1. Experiment Specific Plug-ins 

IGUANA is used by other software projects to de- 
fine experiment-specific views. Among these projects 
are the CMS experiment projects 2 : COBRA - core 
framework, OSCAR - simulation project, ORCA 6] 
- reconstruction project, FAMOS - fast simulation 
project, DDD - detector geometry description and the 
DO experiment project: DOScan. 

The integration with experiment-specific frame- 
works is an IGUANA dependent part, usually a 
sub-system, which is located within the experi- 
ment project. Even though IGUANA core knows 
nothing about these sub-systems, the main driver 
can still load experiment-specific plug-ins providing 
that the location of those plug-ins is listed in the 
IGUANA_PLUGINS environment variable as path de- 
fined by a colon-separated list of directories and the 
experiment-specific shared libraries are available at 
run-time. 



2 http: / /cmsdoc.cern.ch/cmsoo/cmsoo.html 
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Figure 2: DO event display based on IGUANA. 



The projects build plug-ins similar to the described 
above (section |OJ . Usually, each project has a ded- 
icated sub-system called Visualisation for that pur- 
pose. The sub-system contains project specific mod- 
ules, or plug-ins. The kernel loads the modules dy- 
namically as required. Currently a user selects what 
to load at the interactive setup phase or via a resource 
file. 

The plug-ins are normally demand-loaded shared 
libraries but IGUANA also supports statically linked 
applications, therefore no shared libraries need to be 
involved. 

4.2. ORCA Visualisation 

Visualisation for the CMS reconstruction project 
(ORCA) (see Figure ^ and Figure |3J) provides access 
via COBRA plug-ins to both simulated (cmsim) and 
reconstructed event data, and Geant3 based CMS ge- 
ometry as well as reconstructed geometry. Events are 
requested interactively one by one from a specified 
data collection. The IGUANA GUI runs in a sepa- 
rate thread. Communication between the GUI thread 
and the event thread is handled by the COBRA-based 
event processor plug-in. 

The visualisation content is defined at run-time. 
Plug-ins for different ORCA sub-systems can be 
loaded independently. A user can define the content of 



the application in an ASCII text resource file. Various 
visualisation cuts can also be defined in the resource 
file. The on-line configuration editor implemented as 
an IGUANA service allows to change them interac- 
tively or set new configurables during the run. 



4.3. DOScan 



DOScan is an event viewer for DO using IGUANA. 
The DOScan design is based upon the IGUANA IgVis 
module which provides a very flexible set of tools for 
organizing an Opcnlnvcntor scene, creating a GUI to 
control visibility of items in the scene, and centralizing 
picking callback. Items such as detector components, 
hits, tracks, and so forth are implemented as IgQt- 
Twigs and arranged in a hierarchical structure similar 
to the Openlnventor scene graph. This structure is 
represented in the Twig browser that controls visibil- 
ity of graphical objects. 

DOScan makes heavy use of the ability of IgVis to 
support multiple windows with different characteris- 
tics. User demand has led to the development of spe- 
cialized displays as, for instance, in the rj— <f> projection 
of the distribution of energy in the calorimetry. 



MOLT008 



CHEP03, La Jolla, California, March 24-28, 2003 




Figure 3: ORCA visualisation based on IGUANA: Z view (left) of H— > eefifi event and sliced Y view of the same 
event (right). CMS detector description based on Geant3 and reconstructed geometry is shown for the tracker silicon 
detector. Simulated tracks: muons shown with red color, electrons - green, pions - blue, all other particles - cyan. 



4.4. OSCAR Visualisation 



5.1 . LCG Software and Services 



Visualisation for CMS simulation project using 
GEANT4 - OSCAR visualisation - is based on the in- 
teractive visualisation sub- framework of IGUANA for 
GEANT4 described above in section El CMS detec- 
tor geometry is described in XML by DDD - Detector 
Description Database project. This description is con- 
verted to the GEANT4 one and visualised. 



IGUANA team actively participates in the LCG 
project. Part of the software has already migrated 
to SEAL such as the classlib and plug-in manager. 
IGUANA uses services provided by SPI such as Savan- 
nah bug reporting system. POOL is used indirectly 
via experiment specific plug-ins. 



5. TOOLKIT 



IGUANA makes use of suitable existing software 
where possible and integrates the whole in a coherent 
fashion. Application developers select from the toolkit 
only those parts which are relevant for a particular 
application. 

External software used by IGUANA includes the 
3D graphics libraries: OpenGL and Opcnlnventor, the 
Qt toolkit as a GUI kernel, public-domain Qt and In- 
ventor extensions, various packages for plotting and 
interactive analysis, an XML parser, etc. 

Being accessible via IGUANA services with dedi- 
cated GUI extensions, both Oprofile and Jprof are 
used for debugging. IgNominy - an IGUANA 
tool for dependency analysis depends on Graphviz for 
drawing diagrams. Doxygen is used for auto gener- 
ated reference documentation. IGUANA studio print- 
ing services integrate gl2ps for producing high quality 
vector postscript. The team has improved culling al- 
gorithms of the package which reduce the size of the 
printed file dramatically and fed them back to the au- 
thor. 



6. FUTURE PLANS 



IGUANA will provide wider selection of 2D and 3D 
representations and specialized viewers including the 
time snapshots of visualized data, algorithm depen- 
dent views, and animation. 

The project progresses toward coherent physicist 
desktop emphasizing the role of wizards for experi- 
ment specific environment, control center, and other 
services. 

Future possibilities are open for discussion in con- 
text of the LHC LCG project, e.g. PI - Physicist 
Interface project. Among those there are issues of in- 
tegration and future relationship with ROOT, JAS, 
etc. and potential front-end GUI for GRID applica- 
tions. 
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